<TeXmacs|1.99.16>

<project|rehash.tm>

<style|<tuple|tmmanual|british>>

<\body>
  This API is implemented in the module <scm|(rehash hash)>.

  <todo|bring fibers API in line, and perhaps the low-level API as well>

  <subsection|Data types>

  <\explain>
    <scm|(hash-type? <scm-arg|hash-type>)><explain-synopsis|Test if object is
    a hash type>
  </explain|Is <var|hash-type> a hash type? Hash types have a disjoint type,
  separate from symbols and integers. Hash types may be compared with
  <scm|eqv?>.>

  <\explain>
    <scm|(hash? <scm-arg|hash>)><explain-synopsis|Test if object is a hash>
  <|explain>
    Is <var|hash-type> a hash? Hashes have a disjoint type, separate from
    strings, vectors and bytevectors. Hashes may be compared with
    <scm|equal?>.
  </explain>

  <\explain>
    <scm|(raw-hash? <scm-arg|raw-hash>)><explain-synopsis|Test if object is a
    raw hash>
  <|explain>
    Is <var|raw-hash> a raw hash? Raw hashes are like regular hashes, but
    with less sanity checking. In particular, it is not verified whether the
    hash length is reasonable for the hash type and whether the hash type
    exists. Raw hashes are disjoint from regular hashes. Raw hashes may be
    compared with <scm|equal?>.
  </explain>

  <subsection|Conditions>

  <\explain>
    <scm|&hash-string-format-error><explain-synopsis|Bogus string that should
    be representing a hash>

    <\scm>
      hash-string-format-error?
    </scm>

    <scm|hash-string-format-error-string>

    <\scm>
      (make-hash-string-format-error <scm-arg|string>)
    </scm>
  </explain|The string <var|string> (or <scm|#f> if unavailable), that ought
  to be representing a hash or hash type, is actually bogus.>

  <\explain>
    <scm|&null-hash-type><explain-synopsis|Not a real hash / hash type>

    <\scm>
      null-hash-type?
    </scm>

    <\scm>
      (make-null-hash-type)
    </scm>
  <|explain>
    The special \<#2018\>not a hash / not a hash type\<#2019\> value was
    encountered where a hash or hash type was expected.
  </explain>

  <\explain>
    <scm|&bogus-raw-hash><explain-synopsis|The raw hash doesn't represent
    anything>

    <scm|bogus-raw-hash?>

    <scm|(make-bogus-raw-hash <scm-arg|raw-hash>)>
  </explain|The raw hash <var|raw-hash> (or <scm|#f> if unavailable), that
  ought to represent a hash, didn't actually represent a hash.>

  <subsection|Conversion functions>

  <\explain>
    <scm|(hash-\<gtr\>string <scm-arg|hash>)><explain-synopsis|Textual
    representation of a hash>
  <|explain>
    Compute the textual representation of <var|hash>. It is unspecified
    whether the resulting string may be modified.

    <paragraph|Exceptions>

    <\description>
      <item*|<scm|&implementation-restriction>>This implementation does not
      support computing a textual representation of hashes of the type
      <scm|hash> has.\ 
    </description>
  </explain>

  <\explain>
    <scm|(string-\<gtr\>hash <scm-arg|string>)><explain-synopsis|Parse a
    string into a hash>
  <|explain>
    Try to parse <var|string> as the textual representation of a hash.

    <paragraph|Exceptions>

    <\description>
      <item*|<scm|&implementation-restriction>>The implementation does not
      recognise <var|string>.

      <item*|<scm|&hash-string-format-error>><var|string> is known to be
      bogus. E.g., the hash type was identified, but the string was still
      found not to represent anything.

      <item*|<scm|&null-hash-type>><var|string> was <scm|"none">, which will
      never represent a hash.
    </description>
  </explain>

  <\explain>
    <scm|(raw-hash-\<gtr\>hash <scm-arg|raw-hash>)><explain-synopsis|Try to
    interpret a raw hsh>
  <|explain>
    Try to interpret <var|raw-hash> as a regular hash.

    <paragraph|Exceptions>

    <\description>
      <item*|<scm|&implementation-restriction>>The implementation does not
      support the hash type of <var|raw-hash>.

      <item*|<scm|&bogus-raw-hash>><var|raw-hash> doesn't represent any hash.
    </description>
  </explain>

  <\explain>
    <scm|(hash-\<gtr\>raw-rehash <scm-arg|hash>)><explain-synopsis|Convert a
    hash into a raw hash>
  </explain|Interpret <var|hash> as a raw hash.>

  <\explain>
    <scm|(hash-type-\<gtr\>integer <scm-arg|hash-type>)><explain-synopsis|Numeric
    identifier of a hash type>
  <|explain>
    Return the numeric identifier of a hash type, as an exact strictly
    positive exact integer smaller than <math|2<rsup|32>>.
  </explain>

  <\explain>
    <scm|(integer-\<gtr\>hash-type <scm-arg|integer>)><explain-synopsis|Interpret
    an integer as a hash type>
  <|explain>
    Look up a hash type by its numerical identifier.

    <paragraph|Exceptions>

    <\description>
      <item*|<scm|&implementation-restriction>>The implementation does not
      recognise the hash type.

      <item*|<scm|&hash-type-out-of-bounds>><var|integer> was not in
      <math|<around*|[|0,2<rsup|32>-1|]>>

      <item*|<scm|&null-hash-type>><var|integer> was <scm|0> (<samp|none>),
      which will never represent a hash type.
    </description>
  </explain>

  <\explain>
    <scm|(hash-type-\<gtr\>string <scm-arg|hash-type>)><explain-synopsis|Textual
    representation of a hash type>
  <|explain>
    Return the textual representation of a hash type. This always succeeds.
    It is unspecified whether the resulting string may be modified.
  </explain>

  <\explain>
    <scm|(string-\<gtr\>hash-type <scm-arg|string>)><explain-synopsis|Interpret
    a string as a hash type>
  <|explain>
    Look up a hash type by its textual identifier.

    <paragraph|Exceptions>

    <\description>
      <item*|<scm|&implementation-restriction>>The implementation does not
      recognise the hash type.

      <item*|<scm|&null-hash-type>><var|string> was <scm|"none">, which will
      never represent a hash type.
    </description>
  </explain>

  <subsection|Hash types>

  <todo|Basic information on expected length>

  <todo|Figure out how to fit in nix archives>

  <\explain>
    <scm|hash:sha256>
  <|explain>
    <todo|reference>
  </explain>

  <\explain>
    <scm|hash:sha512>
  <|explain>
    <todo|reference>
  </explain>

  <\explain>
    <scm|hash:sha3-256>
  <|explain>
    <todo|reference>
  </explain>

  <\explain>
    <scm|hash:sha3-512>
  <|explain>
    <todo|reference>
  </explain>

  <\explain>
    <scm|hash:blake2s-256>
  <|explain>
    <todo|reference>
  </explain>

  <\explain>
    <scm|hash:fs-regular>
  <|explain>
    <todo|better name>

    <todo|reference>
  </explain>

  <subsection|Making hashes>

  <\explain>
    <scm|><scm|(hash-bytevector <scm-arg|hash-type>
    <scm-arg|bv>)><explain-synopsis|Compute the hash of a bytevector>
  <|explain>
    Hash the bytevector <var|bv> with the hash function <var|hash-type>, and
    return the computed hash.

    <subparagraph|Exceptions>

    <\description>
      <item*|<scm|&not-an-octet-hash>>Raised if the hash function
      <var|hash-type> cannot be used for octet data. (E.g., <var|hash-type>
      is a hash for directories only.)

      <item*|<scm|&implementation-restriction>>Raised if the implementation
      does not support hashing bytevectors with <var|hash-type>.
    </description>
  </explain>

  <\explain>
    <scm|(make-hashing-output-port <scm-arg|hash-type>
    ...)><explain-synopsis|An output port hashing its input>
  <|explain>
    Return two values: a fresh binary soft output port and a thunk. The port
    hashes it input with a few different hash types <var|hash-type>
    <text-dots>. When the port is closed and the thunk is called, the thunk
    returns hashes of type <var|hash-type> <text-dots> (in the same order).
    As a special case, zero <var|hash-type> are allowed.

    <subparagraph|Exceptions>

    <\description>
      <item*|<scm|&not-an-octet-hash>>Raised by
      <var|make-hashing-output-port> if the hash types cannot be used for
      octet data. (E.g., <var|hash-type> is a hash for directories only.)

      <item*|<scm|&not--hashed-yet>>Raised by the thunk if the port wasn't
      closed yet.

      <item*|<scm|&implementation-restriction>>Raised if the implementation
      does not support hashing streams with <var|hash-type> <text-dots>.
    </description>
  </explain>

  <\explain>
    <scm|(hash-input-port! <scm-arg|input> <scm-arg|hash-type>
    ...)><explain-synopsis|Hash all input>
  <|explain>
    Read the binary input port <var|input> from the current position to the
    first end-of-file, and return the computed hashes, of types
    <var|hash-type> <text-dots> (in that order). As a special case, zero
    <var|hash-type> are allowed (in which case <var|input> will still be
    read).

    <paragraph|Exceptions>As this procedure will read from <var|input>,
    input-output exceptions may be raised as well.

    <\description>
      <item*|<scm|&not-an-octet-hash>>Raised (before attempting to read
      anything) if the hash types cannot be used for octet data. (E.g.,
      <var|hash-type> is a hash for directories only.)

      <item*|<scm|&implementation-restriction>>Raised (before attempting to
      read anything) if the implementation does not support hashing streams
      with <var|hash-type> <text-dots>.
    </description>

    Raising these exceptions early may be important in multi-threading
    scenarios.
  </explain>

  <\explain>
    <scm|(make-raw-hash <scm-arg|type-integer>
    <scm-arg|bv>)><explain-synopsis|Construct a raw hash>

    <scm|(make-raw-hash <scm-arg|type-integer> <scm-arg|bv> <scm-arg|offset>
    <scm-arg|length>)>
  <|explain>
    Make a raw hash, with as numeric identifier of the hash functon
    <var|type-integer>, and as underlying bytevector <var|bv>. Optionally, a
    byte range of <var|bv> can be selected with the exact natural numbers
    <var|offset> and <var|length>. A copy of the bytevector will be used to
    make the returned raw hash immutable.

    <paragraph|Exceptions>

    <\description>
      <item*|<scm|&overly-long>>Raised if the length of the bytevector slice
      is considered too large for a hash.

      <item*|<scm|&null-hash-type>><var|type-integer> was <scm|0>
      (<samp|none>), which will never represent a hash type.

      <item*|<scm|&hash-type-out-of-bounds>> <var|type-integer> was not in
      <math|<around*|[|0,2<rsup|32>-1|]>>
    </description>
  </explain>

  <subsection|Destructing hashes>

  <\explain>
    <scm|(hash-type <scm-arg|hash>)><explain-synopsis|Type of a hash>
  </explain|Return the type of a hash <var|hash> (that is, <scm|hash-type?>
  returns <scm|#t> on the result).>

  <\explain>
    <scm|(raw-hash-type <scm-arg|raw-hash>)><explain-synopsis|Numeric hash
    type of raw hash>
  </explain|Return the numerical identifier of the hash type of the raw
  hash<var|> <var|raw-hash>. This is an exact positive integer in the open
  range <math|<around*|(|0,2<rsup|32>|)>>.>

  <\explain>
    <scm|(raw-hash-bv <scm-arg|raw-hash>)><explain-synopsis|Bytevector of a
    raw hash>
  </explain|Return the underlying bytevector of a raw hash. It is unspecified
  whether the resulting bytevector is immutable. If it isn't, writes to the
  returned bytevector will not affect <var|raw-hash>.>
</body>

<\initial>
  <\collection>
    <associate|save-aux|false>
  </collection>
</initial>